feat(onboarding): a fresh install always reaches a workspace; no provider CLI is required (#995) - #1047

…ean Mac (#995 stage 1)

The recorder runs the REAL checkPrerequisites with only the machine's
edges simulated:
- a fresh HOME, where every provider CLI installs on macOS;
- launchd's PATH;
- /bin/sh;
- a temp Electron app path, which for the packaged case holds the
  OpenCode runtime tree #994 ships.

The recordings were taken on main 82babd2, before any policy change,
and show the wall. Both clean machines report ready:false with
blocking [claude, codex], even the packaged one where OpenCode is
bundled and usable, and even though Grok was found.

Without RECORD_FIRST_RUN=1 the test re-runs both clean simulations live
and fails if a provider row no longer matches its recording, so the
fixtures cannot drift from what the probes report. Rows found at a
machine-wide path (this Mac's npm-global Grok under /opt/homebrew) are
recording-machine facts and are not compared. The README explains this.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…first project (#995 stage 2)

Claude Code and Codex were `required`, so a Mac without both met a
SetupGate with no Continue button. The stage-1 recordings show the wall:
- the packaged app on a clean Mac, with OpenCode bundled and usable,
  was ready:false and blocked on [claude, codex];
- so was a Grok-only machine.

Changes:
- `required` is removed from provider descriptors. SetupToolStatus.provider
  marks what the gate must treat as an agent CLI, without the lockout.
- src/shared/setup/readiness.ts is the one policy:
  - usableProviders: found, bundled included;
  - firstSessionKind: the default provider if usable, else the first
    usable one in registry order, else a terminal.
  checkPrerequisites stamps both onto SetupCheckResult, so no consumer
  re-derives them. ready/blocking are gone; nothing blocks.
- Each provider carries a copyable install command and docs URL. These are
  the providers' native installers, since a fresh Mac has no npm or brew.
  Each URL was checked on 2026-09-19. Grok's only published distribution
  is npm.

Tests:
- The recorder now saves the whole result as `check`. The probe rows are
  identical to the baseline recording, and the pre-#995 verdicts are kept
  in baseline-main-82babd21.json.
- readiness.test.ts runs the policy over the recorded machines:
  - packaged clean Mac → opencode;
  - Grok-only → grok;
  - zero providers → terminal, via the one documented edit that unsets
    machine-wide installs;
  - developer machine → claude.
- The live system check asserts the policy on the real probe result. On
  the macOS CI runner that is the genuine zero-provider Mac.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…up can be reopened (#995)

Stages 3–6 of docs/decomposition/onboarding-first-run.md.

- Setup store (features/setup/store.ts): one shared check for the gate,
  the bootstrap and the pickers, with one in-flight probe.
- SetupGate:
  - It opens by itself only when no provider is usable, or when a
    Homebrew-installable helper is missing.
  - "Continue with a terminal" is the explicit acknowledgment. Escape
    does not decide it.
  - Missing providers show a copyable install command and a docs link.
    The manual path override now applies to any missing provider.
- Reopenable: the `open-setup` command, and File › Setup… (added to
  NATIVE_MENU_COMMAND_IDS). The spawn error names that place instead of
  "open Setup", which did not exist after launch.
- Bootstrap:
  - A fresh install waits for the first-run decision instead of spawning
    Claude under the gate.
  - It opens firstSessionKind, and falls back to a terminal if that spawn
    fails, so the run always has a project and autosave.
  - The persisted-fallback recovery shell uses the same verdict without
    waiting.
- The first project's cwd is home when launchd started the app in /.
- Pickers (path picker, new agent, new agent in, provider switch):
  - Missing providers get a "Not installed · File › Setup…" hint but stay
    selectable, since a probe can be wrong.
  - The path picker preselects the machine's first usable provider.

Tests: firstRun.renderer.test.tsx runs the real useWorkspace and bootstrap
and the real SetupGate against the RECORDED checks. The cases:
- no provider: panel, install commands, no spawn until answered;
- a terminal on Continue, and restoreStatus fresh;
- Retry after installing gives an agent;
- the packaged app opens the bundled OpenCode;
- a failed spawn falls back to a terminal;
- Open Setup reopens and re-probes.
Fail-first: 5 of 6 fail against main's bootstrap. Also added:
- PathPickerModal preselect and hint tests on the packaged recording;
- defaultWorkspaceCwd tests;
- catalog governance: 124 commands, 43 approved additions, and the File
  menu plus Setup.

Closes #995

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…mber the answer

Codex review of #1047 (policy/bootstrap lens), CHANGES REQUESTED:

1. BLOCKING. The panel tells users to run OpenCode's installer, which
   writes ~/.opencode/bin and appends its PATH export to ~/.zshrc. The
   login-shell probe runs `$SHELL -lc`, and `zsh -lc` never sources
   .zshrc, so the directory was invisible to both resolution layers: the
   gate said "Not installed", the user ran the command it gave them,
   pressed Retry, and it still said "Not installed" — the one loop this
   feature exists to close. WELL_KNOWN_BIN_DIRS now includes it, and
   ~/.grok/bin for the same reason. A system test installs a stub there
   and fails without the change.
2. The provider-less answer is persisted in setup.json beside the
   skipped helpers. In memory only, it reopened the modal on every
   launch AND in every new window, each being its own renderer process.
3. Only the panel that ASKED records an answer. Closing a panel opened
   from the menu used to durably skip mitmproxy, while Escape in the
   same panel recorded nothing.
4. open-setup no longer closes a panel a parked bootstrap is waiting on:
   a menu item called Setup… must not silently decide "continue with a
   terminal" when Escape and click-outside are refused on purpose.
5. resetSetupStoreForTests settles a parked waiter, so one test's
   bootstrap can no longer resolve into the next one.
6. The live policy assertion is concrete per environment instead of
   restating firstSessionKindFor, which could only fail for a stamping
   mismatch.
7. The fixtures README says that recording rewrites the developer's real
   setup.json, and the plan records the accepted probe-deadline residual.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…indow's bootstrap

Codex review of #1047, P1. awaitFirstRunDecision treated only a live
provider or this run's dismissal as an answer. A machine that had
already chosen "continue with a terminal" therefore parked forever when
a SECOND window opened: its workspace slice is absent, so bootstrap takes
the fresh path, while the panel correctly refused to show itself because
the answer was persisted — leaving nothing to release the wait.

One `decided()` predicate now covers all three ways the question is
already answered, and it is used both before parking and inside the
subscription. The new test opens such a window and expects a terminal
project with no dialog.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The catalog governance counts collide: main gained `enable-goal-loop-mcp`
(#1006) while this branch adds `open-setup` (#995). Both exist now, so
every pinned number moves by one — 125 commands, 119 literal, 44
approved additions — and the three arithmetic comments name both.

Also: `git add -A` re-staged this worktree's stale submodule pointers
over the ones the merge brought in, which `tsc -b` caught as a missing
jumpToLatest on OpencodeTerminalHeadless (#1043's package bump). Every
gitlink is back to main's commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>